Shareware Grab Bag/Shareware Grab Bag.iso/007/d86v311a.arc/03REQ.DOC

Text File | 1987-09-25 | 17KB | 388 lines

CHAPTER 3   REQUIREMENTS AND OPERATION                        3-1

System Requirements for D86

D86 currently requires an IBM-PC or compatible computer, or a
Texas Instruments TI-PC, a Wang PC, Tandy 2000, or a Sanyo 550 or
555 computer.  The computer must be running MS-DOS V2.00 or
later.  The IBM compatibility must exist at the BIOS and video
interface levels: D86 calls the BIOS to obtain keystrokes and
video status information; and, on an IBM-PC, D86 writes directly
to video memory at segment B000 (if the BIOS says monochrome) or
B800 (if color).

D86's memory requirements consist of 64K plus the combined sizes
of D86.COM and A86.COM, plus the memory required by the program
being debugged.  Thus, D86 will work in a 256K system, as long as
there aren't too many resident programs chewing up memory.  If
there are, D86 will tell you.

I will be happy to work with you to add support for your non-IBM-
PC compatible MS-DOS computer.  See the end of this chapter for
the first steps in helping me do so.


Invoking D86

You invoke D86 by issuing the command

   D86 [+V] [progname [command-tail]]

where progname is the name of the program you are debugging.  In
other words, you type a program invocation line just as if you
were about to execute the program without a debugger, except that
you append D86 before the line.

The following sections describe in detail the elements of the D86
invocation line, and how D86 acts on them.



Finding the Program File

On most other debuggers, you have to give the full file name,
with an explicit extension and a specific directory.  With D86,
you don't: D86 uses almost the same algorithm for locating a
program file that COMMAND.COM does:

1. Look for COM, then EXE, then BAT in the current directory.

2. Look for COM, then EXE, then BAT in each directory in turn
   given in the PATH environment variable.
                                                             3-2

The one difference is that D86 will look only for one extension
if you give an explicit extension (and it doesn't have to be COM,
EXE, or BAT).  COMMAND.COM ignores the extension you give-- I
thought that was just too absurd, and didn't duplicate it.

A strange feature that I did duplicate is COMMAND.COM's lack of
concern for whether the program is named COM or EXE.  If the
program file begins with a valid EXE header, it's treated as an
EXE no matter what it is named.  If not, then it's treated as a
COM file.

D86 provides limited support for BAT files.  (That's better than
other debuggers, which provide no support.)  If your program is a
BAT file, D86 reads the first line of the file and pretends that
that was what you typed following "D86" in your invocation.  The
D86 status screen (gotten via Ctrl-S) gives you this line, and
tells you what BAT file it came from.

The BAT file limitations are that D86 doesn't skip over remark
lines, doesn't substitute batch-file parameters, and doesn't
perform console redirection specified in the batch-file line.

You can also invoke D86 with no progname.  The debugger comes up
with no program loaded, allowing you to simply poke around the
machine.

If D86 had a problem loading your program, you'll see all NOPs in
memory instead of instructions.  You can type Ctrl-S to get the
status screen that tells you what the problem was.



Finding the Symbols File

D86 is a symbolic debugger.  It uses a special .SYM file produced
either by the A86 assembler, or by the W command of a previous
D86 debugger session.  When invoked, D86 looks for a file with
the program's name and a .SYM extension.  D86 first looks in the
current directory for this file, and then in each directory
specified in the PATH environment variable.

It is not necessary for the SYM file to exist.  If there is no
SYM file, the debugger simply comes up with no user symbols
defined.  You'll also get no user symbols if the SYM file was not
of a format produced by the current versions of A86 and D86.  If
you were expecting symbols and didn't get any, you can press
Ctrl-S to get the status screen that tells you what the problem
was.
                                                             3-3
Two-Screen Debugging with +V

The +V option can be used if you have both a monochrome and a
color monitor.  You invoke D86 when the operating system is on
the color monitor-- with the +V switch, the debugger will appear
on the monochrome monitor, and program console output will appear
on the color monitor.

Sorry, but the +V option doesn't currently work the other way
around.  I hope to conduct a session on a two-monitor system in
Chicago this fall, to correct the problem.



The D86 Screen Display

When D86 starts up, it generates a full-screen display, and
awaits your debugger commands.

In the top part of the screen is a symbolic disassembly of the
A86 program, with the screen cursor positioned next to the
instruction pointed to by the 8086 instruction pointer.

In the lower right corner is a fixed display of the complete 8086
register set.

At the top of the second column of the register-set display is a
display of the 8086 flags.  Each flag displays as blank if the
flags is off; and a lower-case letter if the flag is on:
          "o" for overflow,
          "d" for direction,
          "i" for interrupts enabled,
          "s" for sign,
          "z" for zero,
          "a" for auxiliary carry,
          "e" for parity even, and
          "c" for carry.

Across the bottom line of the screen is a display of the contents
of the user stack.  The display begins next to the SP register
value, with the number of elements on the stack.  (The stack is
assumed to have 0 elements when SP is at its original value,
which is 0FFFE for COM files, and a value specified in the
header record for EXE files). The number of elements is followed
by a colon, followed by as many of the top stack elements as fits
on the line.  The initial display will have zero elements;
nothing is yet on the stack.

To the right of the registers are 6 lines, numbered 1 through 6.
On these lines, you can generate windows into 8086 memory,
displaying bytes, words, or ASCII text in a variety of formats.
The windows can be located either at absolute memory locations,
or be pointed to by any of the 8086 registers.  The commands you
issue to generate these windows are described in Chapter 6.
                                                             3-4
D86 Commands

There are 5 kinds of activities you perform in D86:

   1. Issuing assembly-language commands for immediate execution
   2. Issuing debugger commands via lines that begin with a
      single letter
   3. Issuing debugger commands via the function, Ctrl, and edit
      keys on your keyboard
   4. Setting up windows displaying memory
   5. Issuing assembly-language commands to enter into memory
      (PatchMem)



Immediate Assembly-Language Commands

A primary part of the D86 command language is the A86 assembly
language. With it, you can jump to different areas of your
program, set your registers, perform arithmetic, and call any of
the procedures of your program.  Simply type in any legal A86
instruction, and it will be executed immediately.

JMP and RET instructions cause the program counter (and thus also
the disassembly) to move to the indicated destination.  CALL
instructions cause the entire procedure to be executed.

WARNING: The immediate-execution feature is a little tricky if
  you are in a multi-segment program, of if you jump to exotic
  parts of the 86 memory space (i.e., into MSDOS, ROM, video
  memory, or the interrupts table). This is because D86 needs a
  buffer in which to put the immediate-execution command.  The
  buffer should be in your program's CS segment, so that commands
  such as jumps and near calls execute correctly.  So D86 must
  always search in CS for a satisfactory buffer.  Here is how
  D86 finds it:

  1. If you declare a label D86_BUFFER, pointing to a buffer
     within your program, then D86 will use that buffer as the
     offset for its immediate instruction.

  2. If not, then if the program's CS register is the same as its
     SS register, D86 will use (SP-300) as its immediate buffer.
     Thus, your stack should have plenty of room (a good practice
     in general).

  3. As a last resort, D86 uses offset 00E0, which points to the
     last 32 bytes of the Program Segment Prefix (PSP).  In that
     case, if you were to issue an immediate command that read
     from a disk file, you would be in trouble, because the disk-
     read operation clobbers the PSP, and the command would then
     not be trapped back to the debugger.
                                                             3-5

  In cases 1 and 3 above, the segment containing the buffer is
  the program's CS segment, unless that is out of range (below
  the program's original CS, or above the top of available
  program memory).  If the program CS is out of range, the
  program's original CS is used instead.  In that case, immediate
  instructions such JMP, RET, and CALL will not work correctly.

  Note that the above caveats do not apply to single-stepping.



Entering Instructions Into Memory

D86 allows you to alter 8086 memory in two ways: first, you can
issue immediate assembly language commands which, when executed,
store values in memory.  The other method is to enter a special
mode, in which you enter instructions directly into 8086 memory.

You enter this mode by typing the F7 (PatchMem) key. The screen
cursor jumps from the left edge of the line at the current
program counter, into the middle of the line where the
instruction is.  You start typing over the instruction, to signal
that you are clobbering the instruction that was there.  If you
did not intend to enter this mode, you can backspace back to the
start of the instruction, and type a carriage-return.

Each line you type in is checked for errors.  If there was an
error, a message is displayed, the cursor remains at the same
location, and you try again. If there was no error, the cursor
moves beyond the newly-assembled line, and you can type in
another line.

To exit the memory-programming mode, you type any of the control-
key commands at the beginning of the line.  (Type carriage-return
if you don't want any actions to be performed.)


Entering Data into 8086 Memory

You can deposit data into the 8086 memory space by using the
programming mode described in the above section.  Simply enter DB
and/or DW statements instead of instructions.  Note that ASCII
strings can be entered with the DB instruction; and that arrays
can be initialized via the DUP operator in a DB or DW statement.
                                                             3-6
Adding Symbols to a Program

Patch-mode also allows you to do something that you cannot do in
immediate-execution mode: add symbols to the program.  You can do
so by either:

   1. Typing in a new symbol-name, followed by a colon; or
   2. Typing in an EQU directive.

There are several uses for this.  First, you might want to create
an abbreviation, by equating a short name to a long one, or to a
hard-to-remember constant value.  Second, you might want to
"reverse engineer" a program for which you have a .COM file, but
not the A86 source code.  Each time you add a label, the
disassembly becomes more readable.  Third, you might want to
label code that you have added in patch-mode.

After you have added symbols to the table, you can save the
resulting expanded table with the W command.  Simply type W
followed by the ENTER key at the main debugger command level.

Forward referencing is allowed when you are in patch mode.  You
must be careful, however, to resolve any forward references you
have made.  In particular, you will cause the assembler to become
very confused if you overwrite a forward reference with some
other code before you resolve the reference.  So don't!



What to Do if D86 Doesn't Work on Your Computer

If D86 does not work properly on your system, I would like to
hear about it.

If you saw no debugger screen at all when you tried executing D86
HEXOUT, try D86 +V HEXOUT.  Let me know what happens then.

I have written a tool called D86CHECK, that outputs information
about your computer system.  Please run D86CHECK to get that
information.  If you are sending me a letter in the mail, you can
direct output to your printer; e.g., D86CHECK >PRN.  If you are
sending me a disk, or a message on the bulletin board, you can
redirect output to a file; e.g. D86CHECK >OUTFILE.

Give me the output to D86CHECK, and tell me as much as you can
about the problems you are experiencing.  Also tell me the brand
and model of your computer.  I'll try to see to it that the
problem is fixed.

Again, my phone number is [phone].  I also receive BBS mail
at [phone] and [phone].  My address is:

   Eric Isaacson
   416 E. University Street
   Bloomington, IN 47401
                                                             3-7
If You'd Like to Be Ambitious

If you are skilled in assembly-language programming, you can
write the BIOS interface routines for D86 yourself, and send them
to me.  That's probably the quickest way you'll get D86 up on
your computer.  I have provided the source module BIOS.8 that
tells you how to do this.  You must add code to BIOS.8 to detect
your machine, take a BIOS keystroke, ring the bell, and copy to
your video memory.  I have also provided a module XBIOS.8 to test
what you have done.  Read the files XBIOS.8 and BIOS.8 for the
details.  If you do not feel up to actually making the
modifications yourself, then you can send me sufficient
documentation about your computer, that would let me do so.  If
you do not know where such documentation exists, ask your
computer dealer or your user's group.

IMPORTANT NOTE: My efforts in porting D86 are done with the
understanding that you will become a registered user.  I would
prefer that you register in advance; if this makes you nervous,
then I will accept a written promise from you that you will
register when I get D86 working on your machine.  (Advance
registrants will get the fastest turnaround.)  I will grant
Sysop-status to those of you who are the first to write the
program for your machine: i.e., if you can persuade five other
users to register (and mention your name when they do so), I'll
refund your registration.

In summary, in order to get D86 up and running on your machine as
quickly as possible, you should send four things:

1. Your registration fee for D86 (and A86, if you plan to use it).

2. The output to D86CHECK as run on your machine.

3. The modified BIOS.8, that produces an XBIOS that works on your
   machine.

4. A list of keycodes returned by your computer as reported by
   XBIOS, for the keys mentioned in the following "Keyboard
   Mapping Chart", as well as any interesting-looking keys in
   your machine that do not exist at all on the IBM-PC.
                                                             3-8
Keyboard Mapping Chart

All ASCII characters should return their ASCII codes.  All
function keys and special keys should return the sum of decimal
112 with the "auxiliary byte" value returned by IBM's BIOS.
These (decimal) values are as shown in the following chart.  So
for example, the F1 key should map to 112+59 = 171 decimal.

F1         59         Alt-0      12        Shift-Tab    15
.                     Alt-hyphen 130       Home         71
.                     Alt-=      131       Up arrow     72
F10        68                              PgUp         73
                      Alt-Q      16        Left Arrow   75
Shift-F1   84         Alt-W      17        Right Arrow  77
.                     Alt-E      18        End          79
.                     Alt-R      19        Down Arrow   80
Shift-F10  93         .                    PgDn         81
                      .                    Insert       82
Ctrl-F1    94         Alt-P      25        Delete       83
.                                          Ctrl-PrtSc  114
.                     Alt-A      30        Ctrl-Left   115
Ctrl-F10  103         Alt-S      31        Ctrl-Right  116
                      .                    Ctrl-End    117
Alt-F1    104         .                    Ctrl-PgDn   118
.                     Alt-L      38        Ctrl-Home   119
.                                          Ctrl-PgUp   132
Alt-F10   113         Alt-Z      44
                      Alt-X      45
Alt-1     120         .
.                     .
.                     Alt-M      50
Alt-9     129